<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN">
<HTML>
<HEAD>
<META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<META name="GENERATOR" content="IBM WebSphere Studio">
<META http-equiv="Content-Style-Type" content="text/css">
<LINK href="css/tigris.css" rel="stylesheet"
	type="text/css">
<TITLE>fragment.html</TITLE>
</HEAD>
<BODY>
<DIV class="app">
<DIV class="h3">
	<h3>How to use custom rule sets with the plug-in</h3>
	<P>
	Using custom rule sets with the plug-in is quite simple. PMD searches the rule sets
	files on the classpath defined for the plug-in. So, to use custom rule sets, they
	must be on the PMD Plug-in classpath.
	</P>
	<P>
	The way to do that with Eclipse is to package the rule sets in a plug-in fragment.
	A fragment is an extension of a plug-in and all the classes and ressource files
	it contains are automatically added to the main plug-in classpath.
	</P>
	<P>
	The steps to add a custom rule set are :
	</P>
	<OL>
		<LI>
		Create a plugin fragment as an extension to the PMD Plug-in
		</LI>
		<LI>
		Optionnaly, develop your rule class implementation
		</LI>
		<LI>
		Create one or more rule set files
		</LI>
		<LI>
		Test the fragment
		</LI>
		<LI>
		Package the fragment
		</LI>
		<LI>
		Install the fragment in the target Eclipse environment
		</LI>
	</OL>
	<P>
	The following details these steps.
	</P>
	
	<BR>
	<div class="h4">
		<h4>1. Create a plugin fragment as an extension to the PMD Plug-in</h4>
		<P>
		The first step is to setup the plug-in development environment. Open the Preferences
		dialog box. Select Target platform in the Plug-in devlopment category. Then push the
		Select All button and click OK to close the window.
		</P>
		<P>
		The second step is to create a plug-in project for the fragment.
		</P>
		<UL>
			<LI>
			Choose the File->New->Project... menu
			</LI>
			<LI>
			Select the Plug-in development Category and the Fragment project item ; click Next
			</LI>
			<LI>
			Give a name to the project ; a plug-in project name is normally formed like a
			package name, for example : com.foo.pmd.rules
			</LI>
			<LI>
			Specify the fragment id ; by default the project name is used.
			Select also the project type. A Java project is required. Specify the name of the
			jar files and modify the default classes and sources directories if needed.
			</LI>
			<LI>
			Choose a blank fragment project and click Finish.
			</LI>
			<LI>
			Ignore the Problem occurred window and click OK.
			</LI>
		</UL>
		<BR>
		<P>
		The last step is to configure the plug-in manifest.
		</P>
		<UL>
			<LI>
			In the project folder, edit the fragment.xml file.
			</LI>
			<LI>
			In the plug-in id field, type
				<PRE>net.sourceforge.pmd.core</PRE>
			In the Plug-in version field type the PMD plug-in version (ex. 3.5.1).
			In the Match Rule field, select how you want to be bound with the PMD Plug-in.
			A good choice is
				<PRE>Greater or equal</PRE>
			so that if the PMD Plug-in is upgraded, the fragment will still be activated.
			<PRE></PRE>
			</LI>
			<LI>
			Save the changes and close the editor.
			</LI>
		</UL>
		<BR>
		<P>
		The more complex task is done ;-)
		</P>
	</div>
	
	<BR>
	<div class="h4">
		<h4>2. Optionnaly, develop your rule class implementation</h4>
		<P>
		Check the PMD official documentation to learn how to develop rule classes.
		</P>
	</div>

	<BR>
	<DIV class="h4">
		<h4>3. Create one or more rule set files</h4>
		<P>
		This step is simply to create one or more XML rule set files. Place them in the source
		directory. Read the PMD documentation to learn how to write rule set files.
		</P>
	</div>
		
	<BR>
	<div class="h4">
		<h4>4. Test the fragment</h4>
		<P>
		Before deploying the fragment, it is necessary to test it. To do that, the simplest
		way is to launch a test Eclipse environment :
		</P>
		<P>
		In the Run menu, select Run as->Run-time workbench. This will launch a secondary
		workbench with all the installed plug-ins and the fragment currently in development.
		In that workbench, create a test Java project to test the rule set. (see step 6 to
		learn how to configure the PMD Plug-in).
		</P>
	</div>
	
	<BR>
	<div class="h4">
		<h4>5. Package the fragment</h4>
		<P>
		Before deploying the fragment, it is necessary to package it. Export the project
		with the export wizard and select Deployable plug-ins and fragments. Select the
		fragment project and specify the zip file that will form the distribution package. 
		</P>
	</div>
	
	<BR>
	<div class="h4">
		<h4>6. Install the fragment in the target Eclipse environment</h4>
		<P>
		Unzip the distribution package on the target environment. If the target environment
		is Eclipse, then the Eclipse install directory must be "eclipse" ; unzip the distribution
		file from the parent directory (the directory in the distribution file begins with
		"eclipse/plugins...").
		</P>
		<P>
		If the target environment is WSAD, unzip the distribution file from the installation
		path of WSAD.
		</P>
		<P>
		To activate the custom rule set, open the preferences window and select the Ruleset selection
		tab in the PMD category. Type the path and name of the custom rule set file in the
		combo box and press the Add rule set button. The custom rule set is added to the list.
		Press OK to close the Preferences dialog.
		</P>
		<P>
		Now, the custom rule set file will be used each time a PMD check will occur.
		</P>
	</div>
</DIV>
</DIV>
</BODY>
</HTML>
